\title{Comparative Programming Languages
Assignment \# 2: Flight Booking DSL
}
\author{
        Philip Dekeulenaer, Sebastian Kerckhof, Adriaan Larmuseau \\
}
\date{\today}

\documentclass[10pt]{article}
\usepackage{graphicx}
\usepackage{amsthm}

\newtheorem{mydef}{Theorem}

\begin{document}
\maketitle


\section{Introduction}
In this report we describe the Domain Specific Language we have built to execute queries on the Adameus airline booking system.\\
In Section \ref{language} we describe the syntax and features of the language.
In Section \ref{impl} we describe how the language was implemented.
Section 4 lists the amount time each of us spent on this project.

\section{The language}\label{language}
We've named our domain specific language AmadeusDsl, as we would constantly mistake the airline booking system for Mozart's first name in our initial correspondence.\\
In Section \ref{lab} we explain the rational behind the language design. In Section \ref{comm} we list all of the available commands for which we then show some advanced usage options in Section \ref{us}.

\subsection{Rationale}\label{lab}
The first and foremost goal of our domain specific language is to convert the systems queries into something readable and understandable. As such any references to the language's ruby origins were left out.\\
The do end statements that would normally signal the start and end of a ruby block are not present in the language itself. They are added automatically and invisibly by a small parser written in \texttt{parser.rb}.\\
The second goal of this domain specific language is to allow the user to write scripts that can be reused with different input. To handle this changing input certain language features were added that interactively ask the user for this input. When correctly used these allow for the writing of some very powerful programs.

\subsection{Commands}\label{comm}
What follows is a list of each possible command together with all the parameters associated to it.
\begin{itemize}
\item \texttt{Book} : Book one or more codes\\
\texttt{Code (<code> | <code> list)} : The hold code(s) to book	\\
\texttt{[Option (:Print | :IgnoreFailure)*]} : Set print and/or failure 
\item \texttt{Cancel} : Cancel one or more bookings\\
    \texttt{Code (<code> | <code> list)} : The booking to cancel\\
\texttt{[Option (:Print | :IgnoreFailure)*]} : Set print and/or failure
\item \texttt{Check} : Check on or more booking codes\\
    \texttt{Code (<code> | <code> list)} : The booking to check\\
	\texttt{[Option (:Print | :IgnoreFailure)*]} : Set print and/or failure
\item \texttt{Seats} : Check the availability of seats on a certain flight\\
    \texttt{On <date>} : Specifies the date\\
    \texttt{Flight <Flightnumber>} : Specifies the flight number\\
    \texttt{Class <Class>} : Specifies the seat class        \\
	\texttt{[Option (:Print | :IgnoreFailure)*]} : Set print and/or failure 
\item \texttt{Destinations} : Retrieve possible destinations\\
   \texttt{From <airport>} Specifies the airport by name, country or code\\
	\texttt{[Option (:Print | :IgnoreFailure)*]} : Set print and/or failure 
\item \texttt{Airports} : Get a list of airports\\
    \texttt{List (:Country | :Code | :City |: All)} : Choose you're resulting values \\
	\texttt{[Option (:Print | :IgnoreFailure)*]} : Set print and/or failure 
\item \texttt{Airlines} : Get a list of Airlines\\
    \texttt{List (:Name | :Code | :All)} : Choose you're resulting values\\
    \texttt{[Option :Print | :IgnoreFailure]} : Prints the results to the console
\item \texttt{Route} : Returns the route of a flight\\
    \texttt{Flight <flightnumber>} : Specifies the flightnumber\\
	\texttt{[Option (:Print | :IgnoreFailure)*]} : Set print and/or failure 
\item \texttt{Days} : Gives the fly days of a flight\\
    \texttt{Flight <flightnumber>} : Specifies the flightnumber\\
	\texttt{[Option (:Print | :IgnoreFailure)*]} : Set print and/or failure
\item \texttt{Flights} : Returns flights between two points\\
    \texttt{From <airport>} : Specifies the airport by name, country or code\\
    \texttt{To <airport>} : Specifies the airport by name, country or code\\
    \texttt{Between <DateA> ,<DateB>} : Sets the dates\\
	\texttt{[Option (:Print | :IgnoreFailure)*]} : Set print and/or failure
\item \texttt{Search} : A very Powerful but slow command allowing you to search for flights with certain conditions\\
    \texttt{On} "Date" :  Specifies the Date\\
    \texttt{[Within "Date"]} : Specifies the outer limit\\
    \texttt{[Sortby (:price|:duration|:hops) = :price]} : The parameter to sort the results of search internally, only the best result is returned\\
    \texttt{From} "airport" : Specifies the airport by name, country or code\\
     \texttt{To} "airport" : Specifies the airport by name, country or code\\
    \texttt{[Via "airport"]} : To "airport" : Specifies the airport by name, country or code by which to hop\\
    \texttt{[Class "class" = "Economy"] }: The seat class\\
    \texttt{[Seats  nv = 1 ]} : The number of seats wanted\\
	\texttt{[Option (:Print | :IgnoreFailure)*]} : Set print and/or failure
\item \texttt{Cheapest} : An alias for Search with SortBy set to :price 
\item \texttt{Shortest} : An alias for Search with SortBy set to :distance
\item \texttt{Connection} : Used to check the availability of connections\\
\texttt{From <airport> | FromCode <code>} : Specify start point\\
\texttt{To <airport> | ToCode <code>} : Specify end point\\
\texttt{On <date>} : Specify the date \\
\texttt{[Option (:Print | :IgnoreFailure)*]} : Set print and/or failure
\item \texttt{Passenger} : Create a passenger to book for \\
\texttt{Gender <gender>} : The passengers gender\\
\texttt{Name <firstname>} : The passengers first name\\
\texttt{SurName <surname>} : The passengers last name \\
	\texttt{[Option (:Print | :IgnoreFailure)*]} : Set print and/or failure
\item \texttt{Hold} : Hold one or more seats on a flight \\
\texttt{On <Date>} : Date of flight \\
\texttt{Flight <code>} : Specify the flight \\
\texttt{Class <class>} : Define the class \\
\texttt{AddPass <passenger>} :Adds a passenger to the booking\\
\texttt{[Option (:Print | :IgnoreFailure)*]} : Set print and/or failure
\item \texttt{Select} : Interactively select an item from a list \\
\texttt{From <dataSource>} : The data to select from\\
\texttt{[Display <param>]} : The parameter to be displayed\\
\texttt{[Return <param>]} : The parameter to be returned\\
\texttt{[Question <quest>]} : A self chosen question to display\\
\texttt{[Option (:Print | :IgnoreFailure)*]} : Set print and/or failure
\item \texttt{Confirm <question>} : Interactive Yes or No prompt to keep the program going
\item \texttt{Print <string>} : Print the string to the console
\end{itemize}
\subsection{Advanced Usage}\label{us}
While the commands can be used as simple standalone operations, it's wise to combine or chain them. As ruby is available to you from the script files this actualy fairly easy. 
The following examples illustrates this :
\begin{verbatim}
a = Airlines
    List :Name
x = Select 
    From a
\end{verbatim}
This example allows the user to interactively select an airline by name into the variable x which can then be used when performing a \texttt{Search} or \texttt{Seats} command. This allows the user to create convenient interactive programs which can be reused at all times. More examples of this can be found in \texttt{full\_booking.ama}.
\section{The implementation}\label{impl}
Our implementation was built and tested on the Windows operating system using \texttt{ruby-1.9.3}.\\
We highlight the basic structure of the language's implementation in Section \ref{bas} and provide a per file description of what can be found there in Section \ref{list}. \\
In Section \ref{data} we list some small errors we encountered in the database.

\subsection{The Basics}\label{bas}
To evaluate our domain specific language we make use of the \textit{instance\_eval} functionality provided to us by ruby. We use it to evaluate both the commands and their parameters.\\
The commands can be found in the file \texttt{amadeusdsl.rb}. After being parsed by \texttt{parser.rb} the script files commands are evaluated by the \textit{AmadeusDsl} class. For each of these command the parameters have been joined into a separate block by our parser and are evaluated by an underlying parser class, located in \texttt{commandparser.rb}. \\
So we basically repeat the same \textit{instance\_eval} trick twice and use our parser to remove every hint of it.

\subsection{File description list}\label{list}
The project follows the standard layout rules for a ruby gem. This is a consequence of the fact that we were at first developing an internal library dsl which of course has to use the ruby gem layout if wishes to  supersede the cruel condition that is uselessness.
The following files are part of the gem structure and can be safely ignored :\\\\
\texttt{CHANGELOG.md}\\
\texttt{LICENSE}\\
\texttt{Rakefile}\\
\texttt{README.md}\\\\
We have written some examples to showcase the functionality of our language, you can find them in the examples folder :
\begin{itemize}
\item \texttt{full\_booking.ama} : A full booking operation and a great example of the language
\item \texttt{air.ama} : The example from Section 2.3
\item \texttt{chaining.ama} : Another example showing the interactive components of the DSL.
\item \texttt{seats.ama} : Displays some seating information.
\item \texttt{search.ama} : showcases the search functionality, is quite slow.
\item \texttt{dates.ama} : allows the user to interactively choose a flight between Brussels and Amsterdam.
\item \texttt{route.ama} : Show cases some functionality not used in the previous examples
\end{itemize}
Running one of these examples can be achieved with the command :
\begin{verbatim}
./eval.rb ./examples/*.ama
\end{verbatim}
The source code can be found in the lib folder. It's separated in a front-end and back-end with the first being located in the lib folder and the latter inside the lib/amadeusdsl folder.
\begin{itemize}
\item \texttt{amadeusdsl.rb} : Implements all the commands, passes the parameters to the command parser file.
\item \texttt{parser.rb} : Implements a simple parser which adds do end to the script file in the necessary places.
\item \texttt{commandparser.rb} : Implements the parameters for each command.
\item \texttt{connection.rb} : Takes care of calling the server and collecting it's reply.
\item \texttt{lookup.rb} : Processes the server replies converting it into a more useful package.
\item \texttt{error.rb} : Handles de errors thrown by the server.
\item \texttt{algorithms.rb} : The algorithms that perform the advanced search features.   
\item \texttt{graph.rb} : Used by algorithms to analyse the flight schedules.
\item \texttt{priorityqueue.rb} : A class found on the internet used by one of our algorithms.
\end{itemize}
The folder tests also contains some small ruby Unit tests that can be run by using rake. They are however very basics tests of some used mostly to figure out certain version incompatibilities in ruby. It's safe to ignore them.

\subsection{Modifications to the Database} \label{data}
There was a small error in the Database with HLN being left out of the airport section but included in the destinations. To solve this we ran the follwing query on the database :
\begin{verbatim}
INSERT INTO  `airlinedb`.`airport` (
`id` ,
`city_id`
)
VALUES (
'HNL',  '28'
);
\end{verbatim}
Another peculiarity we encountered in our tests was the Australian city of 'syndey' instead of 'sydney'.

\section{Time well spent}
\begin{itemize}
\item \texttt{Philip Dekeulenaer} : 21 hours.
\item \texttt{Adriaan Larmuseau} : 24 hours.
\item \texttt{Sebastiaan Kerckhof} : 22 hours.
\end{itemize}
\end{document}